home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / IDLIncludes / IOIterator.idl < prev    next >
Text File  |  1996-05-01  |  4KB  |  120 lines
  1. /*
  2.      File:        IOIterator.idl
  3.  
  4.      Contains:    xxx put contents here xxx
  5.  
  6.      Version:    Technology:    xxx put the technology version here xxx
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __IOITERATOR_IDL__
  19. #define __IOITERATOR_IDL__
  20.  
  21. #include <somobj.idl>
  22. #include <somcls.idl>
  23.  
  24. #ifndef __TYPES_IDL__
  25. #include <Types.idl>
  26. #endif
  27.  
  28. #ifdef __SOMIDL__
  29.  
  30. #if FOR_SYSTEM8_PREEMPTIVE
  31. /* typedefs*/
  32. typedef UInt32                    IteratorDescVersion;
  33.  
  34. /*
  35. ###########################################################
  36.  How to use the IteratorDescVersion
  37. ###########################################################
  38.  Each family will define a k<Family>CurrentIteratorDescVersion constant
  39.  in its *.i file. The client will check the returned IteratorDescVersion
  40.     value against this constant to make sure there's no version mismatch 
  41.      problem.
  42.  Common data structure used by all I/O family iterators
  43. */
  44. typedef SOMLargeStruct            IODeviceRef;                /* Derived from a struct of 16 bytes in size */
  45.  
  46. /*
  47.  a family unique reference number for returned devices.
  48.  this is an opaque field, for now, use the name registry Ref value of the             
  49.     device in question.    
  50.  The IODeviceRef is unique within a family, NOT unique across the entire I/O name space
  51. */
  52. typedef SOMLargeStruct            IOCommonInfo;                /* Derived from a struct of 20 bytes in size */
  53.  
  54. /* IteratorDescVersion versionNumber: version number of the family specific IOIteratorData*/
  55. #endif
  56. /*
  57. ###########################################################
  58.  How to copy name registry ref --> IODeviceRef
  59. ###########################################################
  60. {
  61.     IOCommonInfo            DeviceData;
  62.     RegEntryRef                *anotherReg, *whichDevice;
  63.     anotherReg = (RegEntryRef *)&DeviceData;
  64.     *anotherReg = *whichDevice;
  65. }
  66. ###########################################################
  67.  How to define a family specific IOIteratorData structure
  68. ###########################################################
  69.  struct <FamilyName>IOIteratorData
  70.  {
  71.       IOCommonInfo     IOCI;    
  72.                     // common data for all families    
  73.         f1,            // Individual family specific data
  74.         f2,
  75.         etc...
  76.  };
  77.  Example 1: (A possible implementation for the SCSI iterator)
  78.     struct SCSIIOIteratorData
  79.  {
  80.       IOCommonInfo     IOCI;    
  81.                     // common data for all families    
  82.         UInt32            BusID;
  83.         UInt32            TargetID;
  84.         UInt32            LUN;
  85.  };
  86. ###########################################################
  87.  How to define a family specific iterator function
  88. ###########################################################
  89. OSStatus <FamilyName><IterationSpecification>GetDeviceData 
  90.             (    ItemCount             requestItemCount,
  91.                 FamilyIteratorData     *(&<FamilyName>IOIteratorDataArray[requestItemCount]),                              
  92.                 ItemCount             *totalItemCountPtr );
  93.                 
  94.  For returning ALL devices that the family have access to
  95.  OSStatus <FamilyName><IterationSpecification>GetDeviceData 
  96.             (    UInt32                familySpecificParam,
  97.                 ItemCount             requestItemCount,
  98.                 FamilyIteratorData     *(&<FamilyName>IOIteratorDataArray[requestItemCount]),
  99.                 ItemCount             *totalItemCountPtr );
  100.                 
  101.  For returning a subset of devices, filtered by some family specific parameters
  102.  EXAMPLES:
  103.  OSStatus SCSIGetDeviceData 
  104.             (    ItemCount             requestItemCount,
  105.                 ItemCount             *totalItemCountPtr,
  106.                 SCSIIteratorData     *(&SCSIIOIteratorDataArray[requestItemCount]));
  107.  To get all scsi devices
  108.  OSStatus SCSIBusGetDeviceData 
  109.             (    UInt32                BusID,
  110.                 ItemCount             requestItemCount,
  111.                 ItemCount             *totalItemCountPtr,
  112.                 SCSIIteratorData     *(&SCSIIOIteratorDataArray[requestItemCount]));
  113.  To get all scsi devices that matches the input BusID
  114. */
  115.  
  116. #endif /* __SOMIDL__ */
  117.  
  118. #endif /* __IOITERATOR_IDL__ */
  119.  
  120.